home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / maestixlib.lha / Maestix / maestix-d.adoc < prev    next >
Text File  |  1995-03-29  |  15KB  |  526 lines
  1. TABLE OF CONTENTS
  2.  
  3. (V35) maestix.library/AllocMaestro
  4. (V36) maestix.library/FlushReceive
  5. (V36) maestix.library/FlushTransmit
  6. (V35) maestix.library/FreeMaestro
  7. (V35) maestix.library/GetStatus
  8. (V35) maestix.library/ReceiveData
  9. (V35) maestix.library/SetMaestro
  10. (V38) maestix.library/StartRealtime
  11. (V38) maestix.library/StopRealtime
  12. (V35) maestix.library/TransmitData
  13.  
  14. maestix.library/AllocMaestro                     maestix.library/AllocMaestro
  15.  
  16.    NAME
  17.     AllocMaestro -- Allokiert die Maestro-Soundkarte (V35)
  18.  
  19.    SYNOPSIS
  20.     ^MaestroBase = AllocMaestro (^Tags)
  21.         D0.l                      A0.l
  22.  
  23.    FUNCTION
  24.     Diese Funktion belegt die Maestro-Soundkarte und gewährt dem
  25.     Klient den alleinigen Zugriff.
  26.  
  27.     Die Karte muß als erstes allokiert werden, bevor sie ange-
  28.     sprochen werden darf.
  29.  
  30.     Der Grundzustand nach AllocMaestro() ist:
  31.  
  32.         Input ist INPUT_STD,
  33.         Output ist OUTPUT_BYPASS,
  34.         Studio-Modus ist abgeschaltet,
  35.         Copy-Protection ist aus,
  36.         Emphasis ist aus,
  37.         Quell-Kategorie ist DAT,
  38.         Rate ist 48kHz,
  39.         Validity ist gesetzt,
  40.         die UDBs sind zurückgesetzt.
  41.  
  42.    INPUTS
  43.     Tags            Reserviert für zukünftige Optionen. Momentan
  44.             immer NULL oder ein Zeiger auf TAG_DONE über-
  45.             geben.
  46.  
  47.    RESULTS
  48.     MaestroBase     Zeiger auf die MaestroBase-Struktur (privat)
  49.             oder NULL, wenn die Karte bereits belegt wurde,
  50.             nicht vorhanden ist oder der Speicher nicht
  51.             ausreichte.
  52.  
  53.    NOTES
  54.     Diese Funktion darf nur aus einem DOS-Prozeß aufgerufen werden.
  55.  
  56.    SEE ALSO
  57.     FreeMaestro()
  58.  
  59.    BUGS
  60.     Leider kann nicht verhindert werden, daß eines der MacroSystem-
  61.     Programme (also MaestroBR und Samplitude) die Karte nach einem
  62.     AllocMaestro() immer noch belegen können.
  63.  
  64.     Diese Funktion versucht zwar auch herauszubekommen, ob ein sol-
  65.     ches Programm die Karte bereits belegt hat, und verhindert dann
  66.     seinerseits die Belegung. Der Versuch ist allerdings nicht immer
  67.     erfolgreich! Seit V37 wurde dieser Test wieder entfernt, da er
  68.     bei älteren Maestros manchmal ungerechtfertigt fehlschlug. Die
  69.     Programme AllocMstx und FreeMstx lösen das Problem.
  70.  
  71. maestix.library/FlushReceive                     maestix.library/FlushReceive
  72.  
  73.    NAME
  74.     FlushReceive -- Stoppt Empfang und gibt Msg zurück (V36)
  75.  
  76.    SYNOPSIS
  77.     FlushReceive (^MaestroBase)
  78.                A0.l
  79.  
  80.    FUNCTION
  81.     Der Empfangsvorgang wird gestoppt.
  82.  
  83.     Alle durch ReceiveData() an die Maestix gesendeten Nachrichten
  84.     werden zurückgesendet.
  85.  
  86.    INPUTS
  87.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  88.             AllocMaestro().
  89.  
  90.    RESULTS
  91.  
  92.    NOTES
  93.  
  94.    SEE ALSO
  95.     FlushTransmit(), ReceiveData()
  96.  
  97.    BUGS
  98.  
  99. maestix.library/FlushTransmit                   maestix.library/FlushTransmit
  100.  
  101.    NAME
  102.     FlushTransmit -- Stoppt Sendung und gibt Msg zurück (V36)
  103.  
  104.    SYNOPSIS
  105.     FlushTransmit (^MaestroBase)
  106.                A0.l
  107.  
  108.    FUNCTION
  109.     Der Sendevorgang wird gestoppt.
  110.  
  111.     Alle durch TransmitData() an die Maestix gesendeten Nachrichten
  112.     werden zurückgesendet.
  113.  
  114.    INPUTS
  115.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  116.             AllocMaestro().
  117.  
  118.    RESULTS
  119.  
  120.    NOTES
  121.  
  122.    SEE ALSO
  123.     FlushReceive(), TransmitData()
  124.  
  125.    BUGS
  126.  
  127. maestix.library/FreeMaestro                       maestix.library/FreeMaestro
  128.  
  129.    NAME
  130.     FreeMaestro -- Gibt die Maestro-Soundkarte frei (V35)
  131.  
  132.    SYNOPSIS
  133.     FreeMaestro (^MaestroBase)
  134.              A0.l
  135.  
  136.    FUNCTION
  137.     Nach dem Gebrauch muß der Klient die belegte Karte wieder
  138.     freigeben. Das geschieht durch diese Funktion.
  139.  
  140.     Alle an Maestix gesendete Nachrichten werden zurückgesendet.
  141.     Die FIFOs werden gelöscht, die Karte wird zurückgesetzt und
  142.     geht in den Bypass-Modus über.
  143.     
  144.  
  145.    INPUTS
  146.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  147.             AllocMaestro().
  148.  
  149.    RESULTS
  150.  
  151.    NOTES
  152.     Diese Funktion darf nur aus einem DOS-Prozeß aufgerufen werden.
  153.  
  154.    SEE ALSO
  155.     AllocMaestro()
  156.  
  157.    BUGS
  158.  
  159. maestix.library/GetStatus                           maestix.library/GetStatus
  160.  
  161.    NAME
  162.     GetStatus -- Gibt den Kartenstatus zurück (V35)
  163.  
  164.    SYNOPSIS
  165.     Status = GetStatus (^MaestroBase,Info-Typ)
  166.      D0.l                    A0.l      D0.l
  167.  
  168.    FUNCTION
  169.     Er Zustand vom gewünschten Info-Typ wird zurückgegeben.
  170.  
  171.    INPUTS
  172.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  173.             AllocMaestro().
  174.     Info-Typ        Typ-Code (MSTAT_...), dessen Wert zurückge-
  175.             geben werden soll.
  176.  
  177.    RESULTS
  178.     Status          Status des entsprechenden Typs.
  179.  
  180.    NOTES
  181.  
  182.     Es existieren folgende Info-Typen:
  183.  
  184.     MSTAT_TFIFO     Zustand der Transmitter-FIFO
  185.              - FIFO_Off     -> Transmitter ist aus
  186.              - FIFO_Running -> Übertragung läuft
  187.              - FIFO_Error   -> seit der letzten Abfrage
  188.                        trat ein Fehler auf
  189.  
  190.     MSTAT_RFIFO     Zustand der Receiver-FIFO
  191.              - FIFO_Off     -> Transmitter ist aus
  192.              - FIFO_Running -> Übertragung läuft
  193.              - FIFO_Error   -> seit der letzten Abfrage
  194.                        trat ein Fehler auf
  195.  
  196.     MSTAT_Signal    prüft, ob ein Signal am gewünschten INPUT
  197.             anliegt (BOOL).
  198.  
  199.     MSTAT_Emphasis  gibt an, ob das Eingangssignal mit Emphasis
  200.             aufgenommen wurde (BOOL).
  201.  
  202.     MSTAT_DATsrc    gibt an, ob die Datenquelle ein DAT- bzw.
  203.             DCC-Recorder ist (BOOL).
  204.  
  205.     MSTAT_CopyProh  zeigt, ob ein Urheberrechtschutz vom Quell-
  206.             signal gewünscht wird (BOOL). Ob es sich um
  207.             eine Kopie handelt, läßt sich jedoch nicht
  208.             feststellen.
  209.  
  210.     MSTAT_Rate      gibt die Rate am Eingang an (ULONG).
  211.  
  212.     MSTAT_UDB       [V37] gibt die aktuellen UDBs zurück (UBYTE).
  213.  
  214.    SEE ALSO
  215.  
  216.    BUGS
  217.  
  218. maestix.library/ReceiveData                       maestix.library/ReceiveData
  219.  
  220.    NAME
  221.     ReceiveData -- Empfängt Daten in eine Message (V35)
  222.  
  223.    SYNOPSIS
  224.     ReceiveData (^MaestroBase, ^Message)
  225.             A0.l         A1.l
  226.  
  227.    FUNCTION
  228.     Dies ist die Funktion zur Übertragung von Daten durch die
  229.     Maestro.
  230.  
  231.     Der Platz für die eingehenden Daten wird in einer normalen
  232.     System-Message zur Verfügung gestellt. Diese Message muß einen
  233.     Zeiger auf den Reply-Port vom Klienten haben. Außerdem wird in
  234.     der Message ein Zeiger auf den zu füllenden Puffer sowie dessen
  235.     Länge übergeben.
  236.  
  237.     Diese Message wird nun in die Eingangs-Queue eingehängt. Sollte
  238.     der Empfangsvorgang noch nicht gestartet worden sein, geschieht
  239.     dies danach.
  240.  
  241.     Wenn der Datenpuffer durch die eingehenden Daten gefüllt wurde,
  242.     wird die Message an den Klienten replyed. Er kann nun die Daten
  243.     bearbeiten und anschließend die Message erneut absenden.
  244.  
  245.     Sollten die Messages ausbleiben, wird der Einlesevorgang abge-
  246.     brochen, wenn die Receive-FIFO überläuft.
  247.  
  248.    INPUTS
  249.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  250.             AllocMaestro().
  251.     Message         Zeiger auf eine System-Message mit einem Zeiger
  252.             auf den Datenpuffer für die eingehenden Daten.
  253.  
  254.    RESULTS
  255.  
  256.    NOTES
  257.     Der Datenpuffer muß Public Memory sein und an einer durch 4
  258.     teilbaren Adresse beginnen. Die Datenpuffer-Länge muß mindestens
  259.     10KByte betragen und durch 1024 teilbar sein.
  260.  
  261.     Vorher sollte ein evtl. laufender Realtime-Effekt gestoppt wer-
  262.     den.
  263.  
  264.    SEE ALSO
  265.     TransmitData(), FlushReceive(), StopRealtime()
  266.  
  267.    BUGS
  268. maestix.library/SetMaestro                         maestix.library/SetMaestro
  269.  
  270.    NAME
  271.     SetMaestro -- Stellt die Maestro-Parameter ein (V35)
  272.  
  273.    SYNOPSIS
  274.     SetMaestro (^MaestroBase, ^Tags)
  275.             A0.l       A1.l
  276.  
  277.    FUNCTION
  278.     Die Kartenparameter werden verändert. Hierzu werden der
  279.     Funktion Tags übergeben.
  280.  
  281.  
  282.    INPUTS
  283.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  284.             AllocMaestro().
  285.     Tags            Tags, die die Einstellungen angeben.
  286.  
  287.    RESULTS
  288.  
  289.    TAGS
  290.     MTAG_Input      (ULONG) gibt den Eingang an, den die Maestro
  291.             verwenden soll. Default ist INPUT_STD, was
  292.             den Standard-Eingang verwendet. Dies ist mo-
  293.             mentan der optische Eingang, wird in zukünf-
  294.             tigen Versionen aber vom Benutzer konfigurier-
  295.             bar sein. Mit INPUT_OPTICAL und INPUT_COAXIAL
  296.             kann aber auch gezielt ein Eingang ausgewählt
  297.             werden. INPUT_SRC48K wählt eine interne Quelle,
  298.             welche konstant einen 48kHz-Referenztakt lie-
  299.             fert, unabhängig vom Eingangssignal.
  300.  
  301.     MTAG_Output     (ULONG) gibt an, welches Signal am Ausgang vor-
  302.             liegt. Default ist OUTPUT_BYPASS, womit das am
  303.             gewählten Eingang anliegende Signal direkt zum
  304.             Ausgang weitergeleitet wird. OUTPUT_INPUT gibt
  305.             das vom Encoder codierte Eingangssignal am Aus-
  306.             gang aus. So können gezielt UDBs und CSBs ge-
  307.             ändert werden. Mit OUTPUT_FIFO wird das Signal
  308.             von der Transmit-FIFO an den Ausgang gelegt.
  309.  
  310.     MTAG_SetCSB     (ULONG) Die angegebenen 32 Bit werden als
  311.             Channel Status Bits durch den Encoder ausgege-
  312.             ben. Dieses Tag sollte nur in Ausnahmefällen
  313.             verwendet werden!
  314.  
  315.     MTAG_SetUDB     (ULONG) Die angegebenen 32 Bit werden als
  316.             User Data Bits durch den Encoder ausgegeben.
  317.  
  318.     MTAG_Studio     (BOOL) Ist dieses Tag TRUE, wird in den
  319.             Studio-Modus geschaltet und die CSBs ent-
  320.             sprechend dieser Norm kodiert. Im Heimbereich
  321.             sollte dieser Modus immer FALSE sein (default).
  322.  
  323.     MTAG_CopyProh   (ULONG) gibt an, ob ein Kopieschutz verwendet
  324.             werden soll. Default ist CPROH_OFF, was einen
  325.             Kopierschutz abschaltet. CPROH_ON aktiviert
  326.             den Kopierschutz und erlaubt noch eine digi-
  327.             tale Kopie der Ausgangssignals. CPROH_PROHIBIT
  328.             sperrt eine digitale Aufnahmemöglichkeit.
  329.             CPROH_INPUT schaltet den Kopierschutz ent-
  330.             sprechend dem Eingangssignal aus oder ein.
  331.  
  332.     MTAG_Emphasis   (ULONG) gibt die Emphasis des Ausgangssignals
  333.             an. Default ist EMPH_OFF, was keine Emphasis
  334.             angibt. Standard ist EMPH_50us ( = EMPH_ON);
  335.             im Studio-Modus steht außerdem noch EMPH_CCITT
  336.             und EMPH_MANUAL zur Verfügung. EMPH_INPUT
  337.             wählt die Emphasis entsprechend dem Eingangs-
  338.             signal.
  339.  
  340.     MTAG_Source     (ULONG) gibt den Quellen-Kategoriecode an.
  341.             Default ist SRC_DAT, außerdem sind SRC_CD,
  342.             SRC_DSR, SRC_ADCONV und SRC_INSTR angegeben.
  343.             Mit SRC_INPUT wird gemäß dem Eingangssignal
  344.             zwischen SRC_DAT und SRC_CD umgeschaltet.
  345.  
  346.     MTAG_Rate       (ULONG) gibt die Datenrate an. Default ist
  347.             RATE_48000, ansonsten existieren RATE_44100,
  348.             RATE_32000 und RATE_48000MANU. RATE_INPUT
  349.             wählt die Rate gemäß dem Eingangssignal.
  350.  
  351.     MTAG_Validity   (BOOL) gibt die Gültigkeit des ausgehenden
  352.             Signals an. Ist dieses Tag FALSE, sind die
  353.             Daten ungültig, was von vielen Endgeräten
  354.             erkannt wird.
  355.  
  356.     MTAG_ResetUDB   Wenn dieses Tag angegeben wird, wird die UDB-
  357.             Information gelöscht und eine Ausgabe der
  358.             UDBs unterbunden.
  359.  
  360.     MTAG_ResetLSA   [V37] Wenn dieses Tag angegeben wird, wird die
  361.             Local-Sample-Address gelöscht. Diese findet in
  362.             der Übertragung im Studio-Format verwendung.
  363.  
  364.  
  365.    NOTES
  366.     Beachten Sie, daß MTAG_Rate lediglich in das Ausgabesignal ver-
  367.     woben wird, jedoch keine Rate auf der Maestro einstellt.
  368.  
  369.     Die Maestro ist lediglich in der Lage, eine 48kHz-Rate zu er-
  370.     zeugen (INPUT_SRC48K). Davon abweichende Raten müssen am aus-
  371.     gewählten Eingang angelegt werden.
  372.  
  373.     Stimmt die MTAG_Rate nicht mit dem tatsächlichen Takt überein,
  374.     kann das Signal in der Regel vom Empfänger nicht bearbeitet
  375.     werden.
  376.  
  377.     Achtung: Diese Funktion darf nur aus einem DOS-Prozeß aufgeru-
  378.     fen werden!
  379.  
  380.    SEE ALSO
  381.  
  382.    BUGS
  383. maestix.library/StartRealtime                   maestix.library/StartRealtime
  384.  
  385.    NAME
  386.     StartRealtime -- Startet einen Realtime-Effekt (V38)
  387.  
  388.    SYNOPSIS
  389.     StartRealtime (^MaestroBase, ^Tags)
  390.                A0.l       A1.l
  391.  
  392.    FUNCTION
  393.     Ein Realtime-Effekt wird gestartet. Vorher sollte der entsprech-
  394.     ende Eingang ausgewählt und OUTPUT_FIFO eingestellt werden.
  395.  
  396.    INPUTS
  397.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  398.             AllocMaestro().
  399.     Tags            Tags, die die Effektparameter angeben.
  400.  
  401.    RESULTS
  402.  
  403.    TAGS
  404.     MTAG_Effect     Wählt einen eingebauten Effekt aus (default:
  405.             RFX_Bypass). Effekte siehe Includedatei.
  406.     MTAG_A0         Parameter für die Effekte
  407.     MTAG_A1         Parameter für die Effekte
  408.     MTAG_D2         Parameter für die Effekte
  409.     MTAG_D3         Parameter für die Effekte
  410.     MTAG_CustomCall (APTR) Zeiger auf eine eigene Effekt-Routine.
  411.  
  412.    NOTES
  413.     Die eigene Effekt-Routine bekommt folgende Parameter übergeben:
  414.  
  415.         -> D0 (WORD)    linkes Datenwort
  416.         -> D1 (WORD)    rechtes Datenwort
  417.         -> D2 (ULONG)   siehe MTAG_D2
  418.         -> D3 (ULONG)   siehe MTAG_D3
  419.         -> D6 (ULONG)   Scratch-Register
  420.         -> D7 (ULONG)   Scratch-Register
  421.         -> A0 (ULONG)   siehe MTAG_A0
  422.         -> A1 (ULONG)   siehe MTAG_A1
  423.         -> A2 (APTR)    Rücksprungadresse.
  424.  
  425.     Die Routine liefert:
  426.  
  427.         <- D0 (WORD)    neues linkes Datenwort
  428.         <- D1 (WORD)    neues rechtes Datenwort
  429.  
  430.     Die Register D2 bis D5 und A0 bis A7 dürfen nicht verändert wer-
  431.     den.
  432.  
  433.     Der Rücksprung aus der Effekt-Routine erfolgt mit "JMP (A2)", und
  434.     nicht etwa mit RTS!
  435.  
  436.     Die Effekt-Routine muß im MEMF_PUBLIC-Bereich stehen! Zu beachten
  437.     ist hier, daß ein Task nicht unbedingt im MEMF_PUBLIC-Bereich ge-
  438.     startet wird! Die Routine sollte außerdem in hochoptimiertem As-
  439.     semblercode geschrieben sein.
  440.  
  441.     Wenn die Effektroutine zu langsam ist, stoppt die Realtime-Funk-
  442.     tion automatisch, und MSTAT_TFIFO sowie MSTAT_RFIFO melden
  443.     FIFO_Error.
  444.  
  445.    SEE ALSO
  446.     StopRealtime()
  447.  
  448.    BUGS
  449. maestix.library/StopRealtime                     maestix.library/StopRealtime
  450.  
  451.    NAME
  452.     StopRealtime -- Stoppt den Realtime-Effekt (V38)
  453.  
  454.    SYNOPSIS
  455.     StopRealtime (^MaestroBase)
  456.               A0.l
  457.  
  458.    FUNCTION
  459.     Ein zuvor gestarteter Realtime-Effekt wird durch diese Funktion
  460.     wieder gestoppt.
  461.  
  462.    INPUTS
  463.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  464.             AllocMaestro().
  465.  
  466.    RESULTS
  467.  
  468.    NOTES
  469.     Vor einem TransmitData() oder ReceiveData() muß ein eventuell
  470.     laufender Realtime-Effekt durch diese Funktion gestoppt werden.
  471.  
  472.    SEE ALSO
  473.     StartRealtime()
  474.  
  475.    BUGS
  476. maestix.library/TransmitData                     maestix.library/TransmitData
  477.  
  478.    NAME
  479.     TransmitData -- Überträgt Daten in einer Message (V35)
  480.  
  481.    SYNOPSIS
  482.     TransmitData (^MaestroBase, ^Message)
  483.               A0.l         A1.l
  484.  
  485.    FUNCTION
  486.     Dies ist die normale Funktion zur Übertragung von Daten durch
  487.     die Maestro.
  488.  
  489.     Die abgehenden Daten werden durch eine normale System-Message
  490.     zur Verfügung gestellt. Diese Message muß einen Zeiger auf den
  491.     Reply-Port vom Klienten haben. Außerdem wird in der Message ein
  492.     Zeiger auf den auszugebenden Puffer sowie dessen Länge übergeben.
  493.  
  494.     Diese Message wird nun in die Ausgabe-Queue eingehängt. Sollte
  495.     die Ausgabe noch nicht gestartet worden sein, geschieht dies
  496.     danach.
  497.  
  498.     Wenn die Daten ausgegeben wurden, wird die Message an den Kli-
  499.     enten replyed. Er kann den Pufferbereich nun mit neuen Daten
  500.     füllen und erneut absenden.
  501.  
  502.     Sollten die Messages ausbleiben, wird die Ausgabe abgebrochen,
  503.     sobald die Transmit FIFO vollständig geleert wurde.
  504.  
  505.    INPUTS
  506.     MaestroBase     Zeiger auf die MaestroBase-Struktur von
  507.             AllocMaestro().
  508.     Message         Zeiger auf eine System-Message mit den aus-
  509.             zugebenden Daten.
  510.  
  511.    RESULTS
  512.  
  513.    NOTES
  514.     Der Datenpuffer muß Public Memory sein und an einer durch 4
  515.     teilbaren Adresse beginnen. Die Datenpuffer-Länge muß mindestens
  516.     10KByte betragen und durch 1024 teilbar sein.
  517.  
  518.     Vorher sollte ein evtl. laufender Realtime-Effekt gestoppt wer-
  519.     den.
  520.  
  521.    SEE ALSO
  522.     ReceiveData(), FlushTransmit(), StopRealtime()
  523.  
  524.    BUGS
  525.  
  526.